S I/O SUBSYSTEM 


This section discusses the I/G Subsystem of the Operating System. The 
I/O subsystem comprises a collection of routines that allow you 
to access peripheral and local devices at three different leveis. The 
CIO (Central I/O Utility), provides the highest level» device 
independent access to devices. The second level allows communication 
with the device handlers. The louiest level is the SIO (Serial I/O bus 
Utility) routine. Any lower level access to a device involves the 
direct reading and writing of the hardware registers associated with 
the device. 

The data byte is the basic unit of input/output. A data byte can 
contain either "binary" (non text) Information, or encoded text 
information. The text encoding scheme supported by the OS is called 
ATASCII, derived from the words "ATARI ASCII." Most ATASCII Codes are 
the same as ASCII, with the primary deviations being the control 
Codes. Appendix D shows the ATASCII character set, and Appendices E, 
F, and G show device—specific imp1 ementations for the display, 
keyboard, and printer. 

The \struct ure of the I/O subsystem is shown on the following page. 
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Where: shows a cantrol path. shows the data structure 

required for a path. 

Note the following: 

o The Keyboard/Display/Screen Editor Händlers don't use SIO. 
o The Diskette hand1 er cannot be called directly from CIO. 
o The DCB is shown tuice in the d iagram. 

Figure 5-1 I/O Subsystem Structure Flow Diagram 
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CENTRAL I/O UTILITY 


The Central I/O Utility provides you mith a single interface in ufhich 
to access all of the System peripheral devices in a device-independent 
manner. The minimum unit of data transfer is the data byte. The CID 
also supports multiple byte transfers. All I/O operations are 
per forme d on a "re t urn—to-user—t*/h en—c omp lete" bas i s» there is no way 
to initiate concurrsnt '‘overlapped“ I/O processes. 

I/O is organized by "files»" uihere a file is a sequential 
collection of data bytes. A file can or may not contain textual 
data and it can or may not be organized by "records- " üihere a 
record is a contiguous group of bytes terminated by an EOL (End of 
Line) character. Some files are synonymous utith a device (as with 
the printer and the Screen Editor)» while other devices can contain 
multiple files» each uith a unigue name (as with the disk drive). 

CIO allous you to access up to eight independent device/files 
at one time» because there are eight I/Ö Control Blocks (IOCB 's) in 
the System. Each of the IÖCB's can be assigned to control any 
device/file because there are no preferred assignments» except that 
IOCB #0 is assigned to the Screen Editor at power-up and 
System reset. 

To access a peripheral» you first set up an IOCB for the OPEN 
command» that supplies the system name for the device to be 
accessed (e. g. K: , for the keyboard» P: , for the printer» D:STARS 
for a diskette file named 'STARS'» etc). You then call the CIO» 
telling it to examine the IOCB to find the OPEN information. CIO 
attempts to find the specified device/file and returns a status 
byte indicating the success of the search. If the specified 
device/file can be found by CIO» then CIO stores control 
information in the IOCB. The IOCB is noui used for as long as that 
file is open. 

Once a file is open» it can then be accessed using data-read or 
data-tur ite types of commands» in general» reading can proceed until 
there is no more data to read (End of File) and writing can proceed 
until there is no more medium to störe data on (End of Medium >» 
although neither reading nor writing need proceed to that point. 

The reading and uiriting of data generally occurs into and out of 
usei—supplied data buffers (although a special case allotuing single 
byte transfers using the 6502 A register is provided). 

When there are no more accesses to be performed on an open 
device/file» you perform the close Operation. This 
accomplishes ttuo functions: 

o It terminates and makes permanent an output file (essential 

for diskette and cassette). 


o It releases that IOCB to be used for another I/O Operation. 
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CIO Design Philosophy 


The CIO utility was designed specifically to meet the following 
design criteria. 

o The transfer of data is device independent. 

o Byte—at-a-time f multiple byte and record—a1igned accesses are 

supported. 

o Multiple device/files can be accessed concurrent1y. 
o Error handling is largely device independent. 

o New device handlers can be added without altering the System 
ROM. 


Device Independence 

CIO provides device independence by having a single entry point for 
all devices (and -for all operations) and by having a 
device-independent calling sequence. Once a device/file is opened> 
data tr ans fers occur wi t h no regard to the ac tual device in vo 1 ved. 
Uniform rules for handling byte- and record-oriented data transfers 
allotif the actual device storage block sizes to be transparent to you 


Data Access Methods 

The CIO supports two file access methods: byte-aligned and 
record-aligned. 

Byte-aligned accesses allow you to treat the device/file as a 
sequential byte stream; any number of bytes can be read or dritten 
and the following Operation will continue where the prior one left 
off. Records are of no consequence in this mode< and reads or 
uirites can encompass multiple records if desired. 

Record-aligned accesses allow you to deal with the data stream 
at a higher level* that of the data record or "line of text. '* Each 
and every write Operation creates a single record (by definition). 
Each read Operation assures that the following read Operation 
will start at the beginning of a record. Record-aligned accesses 
cannot deal uith portions of more than one record at a time. 
Record-aligned accesses are useful only with text data or uith 
binary data guaranteed not to contain the EOL character ($9B> as 
data. 

Note that any file can be accessed using the byte-aligned access 
method' regardless of how the file was created. But not all files 
can be successfully read using record-a1igned accesses; the file 

OPERATING SYSTEM CÜ16555 — Section 5 



must contain EGL characters at the end of each record and at no 
other place. 


Multiple Device/File Concurrency 

Up to e igh t device/files can be accessed concurrently using CIO* 
each operating independently of the others. 


Unified Error Handling 

All error detection and recovery occurs within the CIO Subsystem. 
The Status Information that reaches you is in the form of a 
status byte for each device/file. Error Codes are device 
independent as much as possible <see Appendix B). 


Device Expansion 

Devices are known by single character names such as K or P, and a 
number of device handlers are part of the resident System ROM. 
Houiever* additional device handlers can be added to the System 
using the RAM—resident device table; this is normally done at 
pouer—up time as ufith the diskette boot process* but can be done at 
any point in time. 


CIO Calling Mechanism 

The input/output control block <IOCB > is the primary parameter 
passing structure between you and CIO, There are eight IÖCB's 
in the System* arranged linearly in RAM as shoutn beloui: 


+-+ 1 oüj address C03403 

! IOCB 0 l 


i iocb i : 


! IOCB 6 ! 

: IOCB 7 ! 

+-+ high address 


Figure 5-2 CIO Calling Mechanism 
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One IOCB is retiu ired for each open devic e/f i le. Any IOCB can be used 
to control any device/file. although IOCB O is normal ly assigned to 
the Screen Editor (E:), You perform a typical I/O Operation by: 

Inserting appropriate Parameters into an IOCB of your choosing 
o Putting the IOCB number times 16 into the 6502 X register 

o Performing a JSR to the CID entry point CIÖV EE4561. 


CIO returns to you when the Operation is complete or if an 
error was encountered. The Operation status is in the IOCB used. as 
well as in the 6502 Y register. The 6502 condition Codes will also 
reflect the value in the Y register. In some cases a data byte will 
be in the 6502 A register. The X register will remain unchanged for 
all operations and conditions. An e xample is shown below: 

I0CB2X = «20 ; INDEX FOR IOCB #2. 

LDX #I0CB2X 

JSR CIOV 

CPY #0 ;(optional) 

BMI ERROR 

This sector describes each IOCB byte. with its file naitie and 
address. Each IOCB is 16 bytes long. Some bytes can be altered by 
you and some are reserved for use by CIO and/or the device 
handlers. 


Händler ID — ICHID E03403 

The hand1er ID is an index into the System device table (see 
Section 9) and is not user~alterable. This byte is set by CIO as 
the result of an OPEN command and is left unchanged until the 
device/file is closed, at that time CIO will set the byte to «FF. 


Device Number — ICDNO C03413 

The device number is provided by CIO as the result of an OPEN 
command and is not user-alterable. This byte is used to 
distinguish between multiple devices of the same type, such as 
Dl: and D2: , 
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Command Byte — ICCMD C03423 


You set the command byte. It specifies the command to be 
performed by the CIO. This byte is not altered by CIO. 


Status — ICSTA [03433 

The CIO conveys Operation status to you with the command 
Status byte as a result of each and every CIO call. Each and 
every CIO call Updates the command status byte. The most 
significant <sign> bit is a one for error conditions and zero for 
non-error conditions. and the remaining bits represent an error 
number. See Appendix B -For a list of status codes. 


Buffer Address — ICBAL [03443 and ICBAH £03453 

You set this 2-byte pointeri it is not altered by CIO. The 
pointer contains the address of the beginning (low address) of a 
buffer that: 

o Contains data for read and write operations 

o Contains the device/filename specification for the OPEN 
command. 

You can alter the pointer at any time. 


PUT Address — ICPTL [03463 and ICPTH C03473 

The CIO sets this 2-byte pointer at OPEN time to the handler's 
PUT CHARACTER entry point C- 1). The pointer was provided to 
accommodate the people writing the ATARI BASIC Cartridge, and has 
no legitimate use in the System. This variable is set to point to 
CIO's "IOCB not OPEN" routine on CLOSE. Powei—up and 
[SYSTEM. RESET3. 


Buffer Length/Byte Count — ICBLL [03483 and ICBLH C03493 

You set this 2-byte count to indicate the size of the data 
buffer pointed to by ICBAL and ICBAH for read and write 
operations. It is not required for OPEN. After each read or write 
Operation. CIO will set this parameter to the number of bytes 
actually transferred into or out of the data buffer. For 
record-aligned access. the record length can well be less than 
the buffer length. Also an end of file condition or an error can 
cause the byte count to be less than the buffer length. 


Auxiliary Information — ICAX1 [034A3 and ICAX2 [034B3 
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Yöu set these 2-bytes. They contain information that is 
used by fche OPEN command process and/or is device-dependent. 

For OPEN/ tuio bits of ICAX1 are aluays used to specify the OPEN 
direcfcion as shou/n below« where R is set fco 1 for input (read) 
enab 1 e and W is set fco 1 for output (turite) enab I e. 


7 3 2 0 

+ -- +— y —|-|-|-|— 

t I I i I U I p I * * 

t i t i ( W i n t i i 

+ “ + —+—+— 4 '—+—+-+-“+ 

ICAXi is not altered by CIO. You should not alter ICAXI 
once fche device/file is open. 

The remaining bits of ICAXI and all of ICAX2 contain only 
device-dependent data and are explained lafcer in fchis section. 


Remaining Bytes (ICAX3-ICAX6) 

The handler reserves fche four remaining bytes for Processing the 
I/O command for CIO. There is no fixed use for these bytes. They 
are not user-aIterable excepfc as specified by the particular 
device descriptions. These bytes uill be referred to as ICAX3, 
ICAX4, ICAX5 and ICAX6, although there are no equates for those 
names in the OS equafce file. 


CIO Functions 

The CIO supports records and blocks and the handlers Support 
single bytes. All of the system handlers Support one ar more 
of the eight basic functions subject to restrictions based 
upon the direction of data fcransfer (e.g. one cannofc read data 
frorn the printer). The basic functions are: OPEN» CLQSE, GET 
CHARACTERS, PUT CHARACTERS, GET RECORD. PUT RECORD, GET STATUS, 
and SPECIAL. 


OPEN — Assign Device/Filename to IOCB and Ready for Access 

A device/file must be opened before it can be accessed. This 
process links a specific IOCB to the appropriate device 
handler» initia1izes the device/file, initializes all CIO 
control variables, and passes device-specific Options to the 
device hand1er. 
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You set up the following IGCB Parameters prior to calling CIO for an 
OPEN Operation: 

COMMAND BYTE = *03 

BUFFER ADDRESS = pointer to a device/filename specification. 

AUX1 s= OPEN direction bitsj plus device-dependent Information. 

AUX2 « device-dependent information. 

After an OPEN operation> CIO will have altered the following IOCB 
Parameters: 

HÄNDLER ID = index to the System device table; this is 
used only by CIO and must not be altered. 

DEVICE NUMBER — device number taken from the device/filename 
specification and must not be altered. 

STATUS = result of OPEN Operation) see Appendix B for a list 
of the possible Status codes. In genera1< a negative status 
will indicate a failure to open properly. 

PUT ADDRESS = pointer to the PUT CHARACTERS routine for the 
device hand1er just opened. 

It is recommended that this pointer not be used. 


CLOSE — Terminate Access to Device/File and Release IOCB. 

You issue a CLOSE command after you are through accessing a 
given device/file. The CLOSE process completes any pending data 
writes* goes to the device handler for any device-specific 
actionsi and then releases the IOCB. 

You set the following IOCB parameter prior to calling 
CIO: 

COMMAND BYTE = *QC 

The CIO alters the following IOCB Parameters as a result of the 
CLOSE opera tion: 

HANDLER ID = *FF 

STATUS — Result of CLOSE Operation. 

PUT ADDRESS = pointer to "IOCB not OPEN" routine. 


42 


QPERATING SYSTEM C01&555 


Section 5 



GET CHARACTERS — Read n Characters (Byte-Aligned Access) 

The specified number of characters are read from the device/file 
to the user-supp1ied buffer. EGL characters have no termination 
features uhen using this function; there can be no EQL, or mang 
in the buffer after Operation completion. There is a 
special case provided that passes a single bgte of data in the 
6502 A register uhen the buffer length is set to zero. 

You set the f o 1 louing I0CB paramet er s prior to calling CIO: 

COMMAND BYTE * $07 

BUFFER ADDRESS — pointer to data buffer. 

BUFFER LENGTH = number of bgtes to read/ if this is zero> 
the data uill be returned in the 6502 A register only. 

The CIO alters the follouing IOCB Parameters as a result of the 
GET CHARACTERS Operation: 

STATUS - result of GET CHARACTERS Operation. 

BYTE COUNT/BUFFER LENGTH = number of bgtes read to the 
buffer. The BYTE COUNT will aluays equal the BUFFER LENGTH 
except uhen an error or an end-of-file condition occurs. 


PUT CHARACTERS — Write n Characters (Byte-AIigned Access) 

The specified number of characters are uritten from the user—supp1ied 

buffer to the device/file. EOL characters have no buffer 

terminating properties> although they have their Standard meaning 

to the device/file receiving them; no EOL's are generated by CIO. 

There is a special case that all aus a single c harac ter to be 

passed to CIO in the 6502 A register if the buffer length is 

zero. 

You set the follouing IOCB Parameters prior to initiating the PUT 
CHARACTERS operation: 

COMMAND BYTE = $0B 

BUFFER ADDRESS = pointer to data buffer. 

BUFFER LENGTH = number of bgtes of data in buffer. 

The CIO alters the follouing IOCB parameter as a result of the 
PUT CHARACTERS Operation: 

STATUS = result of PUT CHARACTERS Operation. 
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GET RECORD — Read Up To n Characters (Record-Aligned Access) 


Characters are read from the device/file to the user-supplied 
buffer until either the buffer is full or an EQL character is 
read and put into the buffer. If the buffer fills before an EOL 
is read, then the CIO continues reading characters from the 
device/file until an EQL is read,, and sets the Status to 
indicate that a truncated record was read. No EOL will be put at 
the end of the buffer. 

You set the following IOCB parameters prior to calling CIO: 
COMMAND BYTE = *05 

BUFFER ADDRESS = pointer to data buffer. 

BUFFER LENGTH - maximum number of bytes to read (including 
the EOL character). 

The CIO alters the following IOCB parameters as a result of the 
GET RECORD Operation: 

STATUS * result of GET RECORD Operation. 

BYTE COUNT/BUFFER LENGTH * number of bytes read to data 
buffer; this can be less than the maximum buffer length. 


PUT RECORD — Write Up To n Characters <Record-Aligned Access) 


Characters are written from the user-supp1ied buffer to the 
device/file until either the buffer is empty or an EOL character 
is written. If the buffer is emptied without writing an EOL 
character to the device/file, then CIO will send an EOL after the 
last user-supp1ied character. 

You set the following IOCB parameters prior to calling CIO: 
COMMAND BYTE = *09 

BUFFER ADDRESS = pointer to data buffer. 

BUFFER LENGTH = maximum number of bytes in buffer. 

The CIO alters the following IOCB parameter as a result of the 
PUT RECORD Operation: 

STATUS = result of PUT RECORD Operation. 
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GET STATUS — Return Device-Dependent Status Bytes 

The device Controller is sent a STATUS command. and the 
Controller returns four hytes of status Information that are 
stored in DVSTAT CÖ2EA3. 

You set the following IQCB Parameters prior to calling CIO: 
COMMAND BYTE = $OD 


BUFFER ADDRESS = pointer to a device/filename specification 
if the IOCB is not already OFEN; see the discussion of the 
implied OPEN Option be low. 


After a GET STATUS Operation. CIO will have altered the following 
Parameters: 


STATUS — result of GET STATUS Operation; see Appendix B for 
a list of the possible status Codes. 


DVSTAT 


the four—byte response fros the device Controller. 


SPECIAL — Special Function 

Any command byte value greater than $OD is treated by CIO as a 
special case. Since CIO does not know what the function is. CIO 
transfers control to the device handler for complete Processing 
of the Operation. 

The user sets the follouing IOCB parameters prior to 
calling CIO: 

COMMAND BYTE > $GD 

BUFFER ADDRESS - pointer to a device/filename specification 
if the IOCB is not already open, see the discussion of the 
implied OPEN Option below. 

Qther IOCB bytes can be set up. depending upon the specific 
SPECIAL command being performed. 

After a SPECIAL Operation. CIO will have altered the following 
Parameters: 

STATUS - result of SPECIAL Operation; see Appendix B for a 
list of the possible status codes. 

Öther bytes can be altered. depending upon the specific 
SPECIAL command. 
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Implied OPEN Option 


The GET STATUS and SPECIAL commands are treated specially by ClOi 
they can use an already open IOCB to initiate the process or they 
can use an unopened IOCB. IF the IOCB is unopenedi then the 
buFFer address must contain a pointer to a device/Fi1ename 
speciFication* just as For the OPEN command; CIO will then open 
that IOCB# perForm the speciFied command and then dose the IOCB 
agai n. 


Device/Filename SpeciFication 

As part of the OPEN command/ the IOCB buFFer address parameter 
points to a device/Filename speciFication, that is a string oF 
ATASCII characters in the Following Format: 

■Cspec iFication> CdeviceMXnumber>3:CCFi1ename>3<eo1> 

<device> ::= C i DiEIKiP{R!S 
<number> ;:== 1 \ 2 I 3 ! 4 ! 5 16 i 7 ! 8 

<Filename> has device-dependent characteristics. 

<eol> : ; =* $?B 

The fo1lowing devices are supported at this writing: 

C * Cassette drive 

Dl through D8 = Floppy diskette drives * 

E = Screen Editor 
K = Keyboard 
p = 40-c olumn printer 
P2 = 80-column printer * 

RI through R4 = R5-232-C interfaces * 

S = Screen display 

Devices Flagged by asterisks <#> are supported by nonresident 
hand lers. 

IF <numb er> is not speciFiedi it is assumed to be 1. 

The Following examp1 es show valid device/Filename speciFications: 
C: Cassette 

D2:BDAT File 11 BDAT" on disk drive #2 

D:HOLD File "HOLD“ on disk drive #1 

K: Keyboard 
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I/O Example 


The eKample provided in th is section i11ustrates a simple examp1e 
an I/O Operation using the CIO routine. 


i This code segment i1 lustrates the simple example of reading 
i text lines (records) from a diskette file named TESTER on disk 
; drive #1. All symbols used are equated mithin the program 
i although mang of the sgmbols are in the OS equate file. 

; The program performs the follouing steps: 

l 

1. Opens the file 'Dl:TESTER' using IOCB #3. 


J 2. Reads records until an 

> 3. Closes the file. 

i I/O EGUATES 


EOL* 

*9B 

IÜCB3= 

*30 

ICHID* 

*0340 

ICDNO* 

ICHID+1 

ICCOM* 

ICDNO+l 

ICSTA- 

ICCOM+1 

ICBAL= 

ICSTA+i 

ICBAH= 

ICBAL+1 

ICPTL= 

ICBAH+i 

ICPTH= 

ICPTL+i 

ICBLL= 

ICPTH+1 

ICBLH* 

ICBLL+i 

ICAX1* 

ICBLH+1 

ICAX2= 

ICAX1+1 

OPEN= 

*03 

GETREC* 

*05 

CLOSE* 

*oc 

OREAD* 

*04 

OWRIT= 

*08 

EOF* 

*88 

CIOV* 

*E456 


error or EOF is reached. 


i END OF LINE CHARACTER. 
i IOCB #3 OFFSET (FROM IOCB #0). 

i (HÄNDLER ID — SET BY CIO), 
i (DEVICE # — SET BY CIO), 
i COMMAND BYTE, 
i STATUS BYTE — SET BY CIO. 
i BUFFER ADDRESS (LOW), 
i BUFFER ADDRESS (HIGH). 


; BUFFER LENGTH (LOW), 
i BUFFER LENGTH (HIGH). 

; AUX 1. 

; AUX 2. 

j OPEN COMMAND. 

; GET RECORD COMMAND. 

; CLOSE COMMAND. 

i OPEN DIRECTION * READ, 
i OPEN DIRECTION * WRITE. 

; END OF FILE STATUS VALUE. 

i CIO ENTRY VECTOR ADDRESS. 


i FIRST INITIALIZE THE IOCB FOR FILE "OPEN". 

f 

LDX #I0CB3 i SETUP TO ACCESS IOCB #3. 

OPERATING SYSTEM C016S55 — Section 5 






LDA 

STA 


#OPEN 
ICCOM. X 


; SETUP OPEN COMMAND. 


TP 10 


LDA 

#NAME 

; SETUP BUFFER POINTER TO . . . 

STA 

ICBALi X 

i ... POINT TO FILENAME. 

LDA 

#NAME/25& 


STA 

ICBAH, X 


LDA 

#OREAD 

; SETUP FOR OPEN READ. 

STA 

ICAX1, X 


LDA 

#0 

i CLEAR AUX 2. 

STA 

ICAX2, X 


" THE FILE. 


JSR 

CIOV 

; PERFORM "OPEN“ OPERATION. 

BPL 

TP 10 

j STATUS WAS POSITIVE — OK. 

JMP 

ERROR 

i NO — "OPEN" PROBLEM. 

TO READ 

A RECORD. 


LDA 

ttGETREC 

i SETUP "GET RECORD“ COMMAND 

STA 

ICCOM, X 


LDA 

#BUFF 

f SETUP DATA BUFFER POINTER. 

STA 

ICBALi X 


LDA 

#BUFF/256 


STA 

ICBAH, X 



i READ RECORDS. 


LOOP LDA #BUFFSZ 

STA ICBLL,X 

LDA #BUFFSZ/256 
STA ICBLHiX 

JSR CIOV 

BMI TP20 


; SETUP MAX RECORD SIZE 
; ... PRIOR TO EVERY READ. 


i READ A RECORD. 

; MAY BE END OF FILE. 


; A RECORD IS NÖW IN THE DATA BUFFER "BUFF". IT IS TERMINATED BY 
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™rf 0 L*!j? RACTER ' AND THE REC0RD LENÖTH IS IN " IC BLL" and " ICBLH" 
THIS EXAMPLE WILL DO NOTHING WITH THE RECORD JUST READ. 


JMP LOOP 


READ NEXT RECORD. 


NEGATIVE STATUS ON READ — CHECK FOR END OF FILE. 


CPY 

#EOF 

i END OF FILE STATUS? 

BNE 

ERROR 

i NO — ERROR. 

LDA 

STA 

#CLQSE 

ICCOM, X 

i YES — CLOSE FILE. 

JSR 

CIOV 

i CLOSE THE FILE. 

JMP 

* 

; **# END OF PROGRAM *** 


i DATA REGION OF EXAMPLE PROGRAM 


NAME . BYTE "Dl:TESTER", EOL 


BUFFS2- 80 


BUFF= * 

*“ »+BUFFSZ 

. END 

Figgrs 5-3 An I/O Exampla 


80 CHARACTER RECORD MAX 

(INCLUDES EOL). 


READ BUFFER. 
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Device-Specific Information 

Th is section provides device—spec i fi c Information regarding the 
device handlers that interface to CIO. 


Keyboard Händler (K:) 

The fteyboard device is a read only device tuith a hand 1 er that 
Supports the follotuing CIO functions: 


OPEN 

CLOSE 

GET CHARACTERS 
GET RECORD 

GET STATUS (null function) 


The Keyboard Händler can produce the follouiing error statuses: 


$80 — CBREAK3 key abort. 

$Q8 — end-of—file (produced by pressing CCTRL3 3>. 


The Keyboard Händler is one of the resident Händlers. It has a 
set of device vectors starting at location E420. 

The keyboard can produce any of the 256 codes in the ATASCII 
character set (see Appendix F). Note that a fetu of the keyboard 
keys do not generate data at the Keyboard Händler level. These 
keys are described below: 

C/i\3 - The ATARI key toggles a flag that enab1 es/disab 1 es the 
inversion of bit 7 of each data character read. The 
Screen Editor editing keys are exempted from such 
inversion« houiever. 

CAPS - The CCAPS/L0WR3 key provides three functions: 

CSHIFT3CCAPS/LOWR3 — Alpha caps lock. 

CCNTRL3CCAPS/LDWR3 — Alpha CCTRL3 lock. 
CCAPS/LÜWR3 — Alpha unlock. 
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The systsm powers up and will System reset to the alpha 
caps lock option. 


Some key combinations are ignored by the handler, such as 
ECTRL3 4 through CCTRL3 9, CCTRL3 0, CCTRL3 1, CCTRL3 /, and 
all key combinations in that the CSHIFT3 and CCTRL3 keys are 
depressed simultaneously. 

The CCTRL3 3 key generates an EOL character and returns EOF Status 
The CBREAK3 key generates an EOL character and returns BREAK statu 


CIO Function Descriptions 

The device-speci F ic characteristics of the Standard CIO Functions 
(described earlier in this section) are detailed below; 

OPEN 

The device name is K, and the hand1er ignores any device number 
and Filename speciFication, iF included. 

There are no device-dependent option bits in AUX1 or AUX2. 


CLOSE 

No special handler actions. 


GET CHARACTERS and GET RECORD 

The handler returns the ATASCII key codes to CIO as they are 
entered/ with no Facility For editing. 


GET STATUS 

The handler does nothing but set the status to $0i. 


Theory oF Operation 

Pressing a keyboard key generates an IRQ interrupt and vectors to 
the Keyboard Handler's interrupt Service routine (see Section 6). 
The key code For the key pressed is then read and stored in data 
base variable CH C02FC3. This occurs whether or not there is an 
active read request to the Keyboard Händler, and eFFects a one-byt 
FIFO For keyboard entry. See Appendix L (ES) For a discussion oF 
the auto repeat Feature. 
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The Keyb oard Händler monitors the CH variable f or not containing 
the va l ue $FF (empty state) uth enever ther e i s an ac t i ve read 
request for the handler. When CH shows nonempty, the handler 
takes the tcey code from CH and sets CH to $FF again. The key code 
byte obtained from CH is not an ATASCII code and has the 
folloiuing form: 


7 0 

H-J-—+ -■+■——+—I-K 

!C JSi key code ! 


Where: C = 1 if the [CTRL] key is pressed. 

S = 1 if the [5HIFT] key is pressed. 

The remaining six bits are the hardware key code. 


The key code obtained is then converted to ATASCII using the 
first of the follawing rules that applies: 

1. Ignore the code if the C and S bits are both set. 

2. If the C bit is set/ process the key as a [CTRL] code. 

3. If the S bit is setz process the key as a ESHIFT3 code. 

4. If [CTRL] lock is in effecti process alpha characters as CTRL 

codes> all others as lowercase. 

5. IF CSHIFT3 lock is in effect/ process alpha characters as SHIFT 
Codes/ all others as lowerease. 

6. Else f process as lowercase character. 

Then: If the resultant code is not a Screen Editor control codei 
and if the video inverse flag is setz then set bit 7 of the 
ATASCII code (will cause inverse Video when displayed). 
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KEY CODE TO ATASCII CONVERSION TABLE 


Key 

Code 

Key 

Cap 

Lur. 

Oase 

CSHIFTI 

CCTRL] 

Key 

Code 

Key 

Cap 

Lur. 

Case 

SHIFT 

CTRL 

00 

L 

6C 

4C 

OC 

20 

t 

2C 

5B 

00 

01 

J 

6A 

4A 

OA 

21 

SPACE 

20 

20 

20 

02 

i 

3B 

3A 

7B 

22 


2£ 

5D 

60 

03 

— 

— 

— 

— 

23 

N 

6E 

4E 

OE 

04 

— 

— 

— 

— 

24 

— 




05 

K 

6B 

4B 

OB 

25 

M 

6D 

4D 

OD 

06 

+ 

2B 

5C 

IE 

26 

/ 

2F 

3F 

— 

07 

* 

2A 

5E 

1F 

27 

/:\ 

— 

—— 

— 

08 

0 

6F 

4F 

OF 

28 

R 

72 

52 

12 

09 

— 

— 

-- 

— 

29 

— 

— 

— 

-- 

OA 

P 

70 

50 

10 

2A 

E 

65 

45 

05 

OB 

ü 

75 

55 

15 

2B 

Y 

79 

59 

19 

OC 

RET 

9B 

9B 

9B 

2C 

TAB 

7F 

9F 

9E 

OD 

I 

69 

49 

09 

2D 

T 

74 

54 

14 

OE 

- 

2D 

SF 

IC 

2E 

W 

77 

57 

17 

OF 

SS! 

3D 

7C 

ID 

2F 

0 

71 

51 

11 

10 

V 

76 

56 

16 

30 

9 

39 

28 

— 

11 

— 

— 

— 

— 

31 

— 

— 

— 

— 

12 

c 

63 

43 

03 

32 

0 

30 

29 

— 

13 

— 

— 

— 

— 

33 

7 

37 

27 

— 

14 

— 

— 

— 

— 

34 

BACKS 

7E 

9C 

FE 

15 

B 

62 

42 

02 

35 

8 

38 

40 

— 

16 

X 

78 

58 

18 

36 

< 

3C 

7D 

7D 

17 

z 

7A 

5A 

1A 

37 

> 

3E 

9D 

FF 

18 

4 

34 

24 

— 

33 

F 

66 

46 

06 

19 

— 

— 

— 

— 

39 

H 

68 

48 

08 

1A 

3 

33 

23 

9B* 

3A 

D 

64 

44 

04 

1B 

6 

36 

26 

— 

3B 

— 

— **■ 

— — 

— 

IC 

£ESC 3 

1B 

1B 

1B 

3C 

CAPS 

— 

— 

— 

ID 

5 

35 

2 5 

— 

3D 

0 

67 

47 

07 

IE 

2 

32 

22 

FD 

3E 

S 

73 

53 

13 

1F 

1 

31 

21 

— 

3F 

A 

61 

41 

01 


* tCTRLI 3 returns EOF Status. 

A compleroent of this table (ATASCII to keystroke) is given in 
Appendix F. 

Figure 5-4 Keycode to ATASCII Conversion Table 
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Display Händler <S: > 

The display device is a read/urite device with a Händler 
that supports the follouing CIO functions: 


OPEN 

CLOSE 

GET CHARACTERS 
GET RECORD 
PUT CHARACTERS 
PUT RECORD 

GET STATUS (null Function) 

DRAN 

FILL 


The Display Händler can produce the follouing error statuses: 

$84 — Invalid special command. 

$BD — Cursor out-of-range. 

$91 — Screen mode > 11. 

$93 — Not enough memory for screen mode selected. 

The Display Hand 1er is one of the resident Händlers* and 
therefore has a set of device vectors starting at location E410. 


Screen Modes 

You can operate the display screen in any of 20 
conf igurat ions (modes 1 through 8» uith or uithout split 
screen; plus mode 0* and modes 9 through 11 uithout split 
screen). Mode O is the text displaying mode. Modes 1 through 
11 are all graphics modes (although modes 2 and 3 do display a 
suhset of the ATASCII character set). Modes 9 through 11 
require a GTIA Chip to be installed in place of the Standard 
CTIA Chip. 


TEXT MODE 0 

In text mode 0 the screen is comprised of 24 lines of 40 
characters per line. Program alterable left and right margins 
limit the display area. They default to 2 and 39 (of a possible 0 
and 39). 
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A program-controllable Cursor shouis the destination of the next 
character fco be oufcput onfco the screen. The Cursor is visible as 
the inverse Video represenfcation of the current character at the 
destination position. 

The text screen data is internally organized as variable length 
logical lines. The internal representation is 24 lines when the 
screen is cleared. Each EOL marks the end of a logical line as 
text is sent to the screen. If more than 3 physical lines of text 
are sent» a logical line will be formed every 3 physical lines. 
The number of physical lines used to comprise a logical line <1 
to 3) is always the minimum required to hold the data for that 
logical line. 

The text screen "scrolls" upward tuhenever a text line at the 
bottom row of the screen extends past the right margin, or a text 
line at the bottom row is terminated by an EOL. Scrolling removes 
the entire logical line that Starts at the top of the screen» and 
then moves all subsequent lines upward to fill in the void. The 
Cursor also moves upward, if the logical line deleted exceeds one 
physical line. 

All data going to or coming from the text screen is represented 
in 8-bit ATASCII Code as shown in Appendix E. 


TEXT MODES 1 AND 2 

In text rnodes 1 and 2 the screen comprises either 24 lines of 20 
characters (mode i>, or 12 lines of 20 characters (mode 2). The 
left and right margins are of no consequence in these modes and 
there is no visible Cursor. There are no logical lines associated 
with the data and in all regards these modes are treated as 
graphics modes by the handler. 

Data going to or coming from the screen is in the form shown 
below: 


7 0 

+-+-+-+— 

1 c i D ! 

+—i— h— t— t- ——i—f. 

Where:C is the color/charactei—set select field 
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c 

Value 

Color 

(default) 

Color 
Register 
(see 

Appendix 
H) 

Character 

Set 

CHBAS=*EG 

Character 

Set 

CHBAS=*E2 

0 

g r een 

(PF1 ) 

i — 

? 

CHEART3 CARROW] 

1 

gold 

(PFO) 

f — 

? 

CHEART3 CARR0W3 

2 

gold 

< PFO) 

e - 


C DIAMÖND3 C TR IANGLE] 

3 

gr een 

< PF1) 

S “ 


C DIAMÖND 3 C TR IANGLE] 

4 

red 

(PF3) 

i ~ 

? 

CHEART3 CARROW3 

5 

blue 

(PF2) 

i — 

-> 

CHEART3 CARROW3 

6 

blue 

(PF2) 

@ - 


C DIAMOND 3 C TR IANGLE 3 

7 

red 

< PF3) 

@ - 


C DIAMOND 3 C TR IANGLE 3 


D is a 5—b i t truncated ATASCII Code that selects the specific 
character mithin the set selected by the C field. See Appendix E 
for the graphics representations of the characters. 

Data base variable CHBAS CG2F43 allows for the selection of 
either of ttuo data sets. The default value of $EG provides the 
Capital letters* numbers and punctuation characters; the 
alternate value of $E2 provides lowercase letters and the special 
character graphics set. 


Figure 5-5 Text Modes 1 and 2 Data Form 


GRAPHICS MODES (Modes 3 Through 11) 

The screen has varying physical characteristics for each of the 
graphics modes as shown in Appendix H. Depending upon the mode> a 
1 to 16 color selection is available for each pixel and the 
screen size varies from 20 by 12 (lowest resolution) to 320 by 
172 (highest resolution) pixels. 

There is no visible Cursor for the graphics mode output. 

Data going to or coming from the graphics screen is represented 
as 1 to 8-bit Codes as shomn in Appendix H and in the GET/PUT 
diagrams following. 


SPLIT-SCREEN CONFIGURATIONS 

In split-screen configurations, the bottom of the screen is 
reserved for four lines of mode 0 text. The text region is 
controlled by the Screen Editor/ and the graphics region is 
controlled by the Display handler. Two Cursors are maintained in 
this configuration so that the screen Segments can be managed 
independently. 
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To operate in split-screen mode* the Screen Editor must first be 
opened and then the Display Hand 1er must be opened using a 
separate IQCB (uith the split-screen Option bit set in AUXI). 


CIG Function Descriptions 

The device-specific charac ter i s t i cs of the Standard CIO -Functions 
(described earlier in this section) are detailed bei atu: 


GFEN 

The device name is S* and the handler ignores any device numher an« 
filename specification* if included. 


The handler supports the follotuing options: 

7 O 

+ -+—(.—j.—^^— y. 

auxi : iCiS!w:R{ \ 

+ “ + —h—*—h—1-1-— b—b 

Where: C — 1 indicates to inhibit screen clear on OPEN. 

S = 1 indicates to set up a split-screen configuration (for 
modes 1 through 8 only >. 

R and W are the direction bits (read and turite). 

7 0 

H-1-1—+—► — ■+• — + “+ — + 

AUX2 : { mode ä 

Where: mode is the screen mode (0 through 11). 

Note: If the screen mode selected is 0* then the AUXI C and 
S options are assumed to be 0. 

You share memory utilization uiith the Display Handler 
information. Sharing is necessary because the Display Handler 
dynamically allocates high address memory for use in generating 
the screen display* and because different amounts of memory are 
needed for the different screen modes. Prior to initiating an 
OPEN command the variable APPMHI COÖÖEI should contain the 
highest address of RAM you need. The Screen handler 
tui 11 open the screen only if no RAM is needed at or bei out that 
ad dr ess. 

Upon return from a screen OPEN* the variable MEMTOP CÖ2E53 ui 11 
contain the address of the last free byte at the end of RAM 
memory prior to the screen-req.uired memory. 
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As a resul t of every OPEN command, the follouiing screen variables 
ars alteTed: 

The text curso-r is enabled (CRSINH = 0>. The tabs are set to 
the de fault settings (2 and 39). The color registers are set 
to the default values (shoiun in Appendix H). 

Tabs are set at positions 7/15.23,31,39/ 

47/ 55, 63/ 71, 79, 87, 95, 103/ 111, 119. 


CLOSE 

No special Kandier actions. 


GET CHARACTERS and GET RECORD 

Returns data in the following screen mode dependent forms, uihere 
each byte contains the data for one Cursor position <pixel); there 
is no facility for having the hand1er return packed graphics data. 


7 0 


\ ATASCII : 

+"+-+“‘+“+“- 4 '“+“-+“+ 


Mode 0 


* C * D ! Modes 1,2 — C = color/data 

+ set. 

D = truncated ATASCII. 


+-+— 

! zero i D I Modes 3,5,7 — D = color. 


+ + 4 — + — +—+ — + — + — + —*+ 

i zero iD! Modes 4,6,8 — D = color. 


+-+-+-+“+-+-+-+-+ 
i zero ! D ! 

+ — 4 - 1 - 1 - 1 —+--+— 1 -~ + 


Modes 9,10,11 — D = data. 


Figure 5-6 Graphics Mode 3-11 GET Data Form 


The Cursor moves to the next position as each data byte is 
returned. For mode 0, the Cursor will stay within the specified 
margins; for all other modes, the Cursor ignores the margins. 
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PUT CHARACTERS and PUT RECORD 


The Händler accepts display data 
dependent formsr there is no faci 
graphlcs data in packed form. 


7 0 

+ _ + _ + _ + „ + _ + _ + „ + _ + 

i ATASCII ! 

i C J D ! 


+— ^ —j.— t 

J ? i D l 

J ? iDI 

—r-—h-H—+-H-h—t- 

+—f—h~+—h—— h—b 

\ ? ! D i 


n the following screen mode 
i ty for the Händler to receive 

Mode 0 

Modes 1(2 — C * calor/data 

seti 

D = truncated ATASCII. 

Modes 3, 5, 7 — D = color, 

Modes 4>6iS — D * color. 

Modes 9, 10, 11 — D = data. 


Figure 5-7 Graphics Mode 3-11 PUT Data Form 


NOTE: For all modes, if the output data byte equals $9B (EÜL), that 
byte drill be treated as an EDL character r and if the output 
data byte equals $7D (CLEAR) that byte drill be treated as a 
screen-clear character. 

The Cursor moves to the ne x t Cursor Position as each data byte is 
uiritten. For mode Ö, the cursor will stay dtithin the specified 
margins; for all other modes, the Cursor ignores the margins, 

While outputting, the Display Händler monitors the keyboard to 
detect the pressing of the CCTRL3 1 key combination. When this 
occurs, the Händler loops internally until that key combination 
is pressed again: This effects a stop/start function that 
freezes the screen display. Note that there is no ATASCII code 
associated with either the CCTRL1 1 key combination or the 
start/stop function. The stop/start function can be controlled 
only frotn the keyboard (or by altering database variable CH as 
discussed in Appendix L, E4>. 
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GET STATUS 


No handler action except to set the Status to *01. 


DRAU 

This special command drauis a simulated "straight" line fram the 
current Cursor position to the location specified in ROWCRS 
C0054] and CÖLCRS 10055], The color of the line is taken from the 
last character processed by the Display Händler or Screen Editor. 
To force the color» störe the desired value in ATACHR C02FB]. At 
the completion of the command» the Cursor will be at the location 
specified by RÜUCRS and CQLCRS. 

The value for the command byte for DRAU is *11. 


FILL 

This special command fills an area of the screen defined by two 

lines ui th a specified color. The command is set up the same as 

in DRAU» but as each point of the line is drawn, the routine 

Scans to the right performing the procedure shoutn be 1 oui (in 

PASCAL notation): 

UHILE PIXEL CROW,COL] = O DO 
BEO IN 

PIXEL CROW,COL] := FILDAT; 

COL := COL + 1; 

IF COL > Screen right edge THEN COL := 0 
END; 

An examp le of a FILL Operation is shown beiow: 



+ 


+ 2 


Where: represents the fill Operation. 

'+' are the line points, ui th ' +' for the endpoints. 


1 

2 

3 

4 


set cursor and plot point, 

set Cursor and DRAU line. 

set Cursor and plot point. 

set fill data value, set cursor, and FILL, 
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FILDAT C02FD3 contains the fill data, and ROWCRS and COLCRS 
contain the Cursor Coordinates of the line endpoint. The value 
in ATACHR C02FB3 uill he used to drauj the linei ATACHR aluays 
contains the last data read or urittem so if the steps above 
are folloued exactly, ATACHR uill not have to be modified. 

The value for the command byte for FILL is $12. 


User-Alterab1e Data Base Variables 

Certain functions of the Display Hand 1er r eq_uir e you to 
examine and/or alter variables in the OS database. The follouing 
describes some of the more common ly used handler var iab 1 es. (see 
Appendix L, Bi-55, for additional descriptions). 


Cursor Position 

Tuo variables maintain the Cursor position for the graphics 
screen or mode O text screen. ROWCRS COQ543 maintains the display 
rou number; and COLCRS C00553 maintains the display column 
number. Both numb ers ränge from O to the ma ximum numb er of 
rous/eolumns, - 1. The Cursor can be set outside of the defined 
text margins uith no ill effect. You can read and write this 
region. The home position (Q,0> for both text and graphics is the 
upper left corner of the screen. 

ROWCRS is a single byte. COLCRS is maintained at 2-bytes, uith 
the least significant byte being at the 1ouer address. 

When you alter these variables, the screen representation 
of the Cursor uill not move until the next I/O Operation 
involving the display is performed. 


Inhibit/Enable Visible Cursor Display 

You can inhibit the display of the text Cursor on the screen 
by setting the variable CRSINH C02F03 to any nonzero value. 
Subsequent I/O uill not generate a visible Cursor. 

You can enable the display of the text Cursor by setting 
CRSINH to zero. Subsequent I/O uill then generate a visible 
Cursor. 


Text Margins 

The text screen has user-a1terable left and right margins. The OS 
sets these margins to 2 and 39. The variable LMARGN E00523 
defines the left margin, and the variable RMARGN E00533 defines 
the right margin. The leftmost margin value is 0 and the 
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righ tmost marg in va lue is 39. 


Th e margin va1ues inclusive ly d efine the useable portion of the 
screen for all operations in that you do not explicitly 
alter the Cursor location variables as described prior to this 
paragraph. 


Color Control 

The OS Updates hardware color registers using data front the OS 
data base as part of normal Stage 2 VBLANK processing (see Section 
6). Sh Odin be 1 ow are the data base var iable namest the har d wäre 
register names< and the function of each register. See Appendix H 
for the mode dependent uses for the registers. 


Data Base 

Hardware 

Func tion 


COLORO 

COLPFO 

PFO 

— Playfield 0. 


COLOR1 

COLPF1 

PF1 

— Playfield 1. 


C0LQR2 

C0LPF2 

PF2 

— Playfield 2. 


COLOR3 

C0LPF3 

PF3 

— Playfield 3. 


C0L0R4 

CQLBK 

BAK 

— Playfield background 

PCOLRO 

COLPMO 

PMO 

— Player/missile 

0. 

PCOLR1 

COLPM1 

PMi 

— Player/missile 

1 . 

PC0LR2 

C0LPM2 

PM2 

— Player/missile 

2. 

PC0LR3 

COLPM3 

PM3 

— Player/missile 

3. 


Theory of Operation 

The Display Händler automatically sets up all memory resources 
required to create and maintain the screen display at OPEN time. 
The screen generation hardware requires that two distinct data 
areas exist for graphics modes: 1) a display list and 2) a 

screen data region. A third data area must exist for text modes. 
This data area defines the screen representation for each of the 
text characters. Consult the ATARI Home Computer 

Hardware Manua1 for a complete underStanding of the material that 
i s to fo 11 otit. 
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The simplified block diagram belou shous the re lationships 
betuieen the memory and hardware registers used to set up a screen 
display (without player/missile graphics) by the OS Note that 
the Hardware registers allow for many other poss i b i 1 i t ies. 


DATA BASE 


HARDWARE 

VARIABLE 


REGISTER 
<Updated every 
VBLANK) 

+- 



i MEMTOP 

1 

1 


+ 

( 

■f 

! 



-+ 



I +- 

t I 
« I 

i Display 

! List 


+ - 

t 

[ 

: Screen Data 

< Graphics 
l and/or 
! Text 

+ - 

End of RAM memory 
+- 


+— 

f 

i 

SDLSTL 

- + 

I 

1 

+“ 

i 

i 

DLISTL 

"+ I 

1 i 

1 ■ 

+ 

1 

t 

t 

SDLSTH 

+- 

1 

l 

r 

— >+ 

i 

t 

t 

DLISTH 

+ - + 

t 

f 

1 






i 


+— 


!<- 


: 


SAVMSC 


+ 

t 


t +- 
I 

■+ 


+ 


-—-+->- } 

i E CHBAS=EO i->i CHBASE +-+ 

| -*• —--———► -i --—— + 


+- + -+ 

1 Specials and! EOOO 

E Numbers ! 

+ - + 

E Capital i El00 

! Letters ! 


E Special ! E2O0 

! Graphics ' 

+ - + 

! Lowercase i E300 

! Letters ! 
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+-+ 

! COLOR 0 i 


I COLOR 1 ! 

! COLOR 2 ! 

: COLOR 3 I 
i COLOR 4 ! 
+-+ 


i COLPFO 
>! COLPF1 
I C0LPF2 
! C0LPF3 
! COLBK 


Figure 5-8 Screen Display Block Diagram 

The following re lationships are present in the preceding diagram: 

1. Data base variables SDLSTL/SDLSTH contain the address of 
the current display list. This address is stored in the 
hardutare display list address registers DLISTL and DLISTH 
as part of the VBLANK process. 

2. The display list itself defines the characteristics of the 
screen to be displayed and points to the memory containing 
the data to be displayed. 

3. Data base variable CHBAS contains the MSB of the base address 
of the character representations for the character data (text 
modes only>. 

The default value for this variable is $E0. This variable 
declares that the character representations Start at memory 
address EOOO (the character set provided by the OS in ROM). 
Each character is defined as an 8X8 bit matrix, requiring 8 
bytes per character. 1024 bytes are required to define the 
largest set, since a character code contains up to 7 
significant bits (set of 128 characters). The OS ROM contains 
the default set in the region from EOOO to E3FF. 

All character codes are converted by the handler from ATASCII 
to an internal code (and vice versa), as shown belou: 


ATASCII 
CODE 

00- 1F 
20-3F 
40-5F 
60-7F 
8Ö-9F 
AO-BF 
CO-DF 
EO-FF 


INTERNAL 

CODE 

40-5F 
00-1F 
20-3F 
60-7F 
CO-DF 
8Q-9F 
AO-BF 
EO-FF 
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The character set in ROM is ordered by internal code order. Three 
considerations differentiate the internal code from the external 
< ATASC11> code: 

ATASCII codes for all but the special graphics characters were to 
be simiiar to ASCII. The alphabetic, numerier and punctuation 
character codes are identical to ASCII. 

In text modes 1 and 2 it was desired that one character subset 
include Capital lettersi numbersi and punctuation and the other 
character subset include lowercase letters and special graphics 
characters. 

The codes for the Capital and lowercase letters were to be 
identical in text modes 1 and 2. 

Database variables CÜLQRO through CGLÜR4 contain the current 
color register assignments. Hardware color registers receive 
these values as part of the stage 1 VBLANK processr thus 
providing synchronized color changes (see Appendix H>. 

Database variable SAVMSC points to the lowest memory address of 
the screen data region. It corresponds to the data displayed at 
the upper left corner of the display. 

When the Display Händler receives an open commandi it first 
determines the screen mode from the OPEN IOCB. Then it allocates 
memory from the end of RAM downward (as specified by data base 
variable RAMTOP). first for the screen data and then for the 
display list. The screen data region is cleared and the display 
list is created if sufficient memory is available. The display 
list address is stored to the database. 
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Screen Editor (E: ) 


The Screen Editor is a read/write handler that uses the Keyboard 
Händler and the Display Handler to provide "1ine-at-a-time“ input 
with interactive editing functions» as we 11 as formatted output. 


The Screen Editor supports the following CIO functions 

OPEN 

CLOSE 

GET CHARACTERS 
GET RECORD 
PUT CHARACTERS 
PUT RECORD 

GET STATUS (null function) 


See Keyboard Handler and Display Handler Sections Tor a 
discussion of Screen Editor error statuses. 

The Screen Editor is one of the resident Händlers» and 
therefore has a set of device vectors starting at location 
E4Q0. 

The Screen Editor is a program that reads key data from the 
Keyboard Hand 1er and sende each character to the Display Hand 1er 
for immediate display. The Screen Editor also accepts data from 
you to send to the Display Händler» and reads data from the 
Display Hand 1er (not the Keyboard Hand 1er) for you. In fact» 
the Keyboard Handler» Display Handler, and the Screen Editor are 
all contained in one monolithic hunk of code. 

Most of the behaviors already defined for the Keyboard Handler 
and the Display Hand 1er apply as we 11 to the Screen Editor: The 
discussions in this Section will be limited to deviations from 
those behaviors» or to additional features that are part of the 
Screen Editor only. The Screen Editor deals only with text data 
(screen mode 0). This Section also explains the split—screen 
configuration feature. 

The Screen Editor uses the Display Handler to read data from 
graphics and text screens on demand, You use the Screen 
Editor to determine when the program will read Screen data, and 
where upon the screen the data will be read from. You 
first locates the Cursor on the screen to determine the screen 
area to be read; you then press the CRETURN1 key to determine 
when the program will begin to read the data indicated. 
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When the CRETURN1 key is pressed, the entire logical line mithin 
that the Cursor resides is then made available to the calling 
program: Trailing blanks in a logical line are never returned as 
data, houever. After all of the data in the line has been sent to 
the caller (this can entail multiple READ CHARACTERS functions if 
öesired), an EOL character is returned and the Cursor is 

positioned to the beginning of the logical line following the one 
just read. 


CIO Function Descriptions 

The device-specific characteristics of the Standard CIO 
functions are detailed below: 


OPEN 

The device name is E, and the Screen Editor ignores anu 
device number and filename specification, if included. 

The Screen Editor Supports the following Option: 


7 0 

+—+—h—^—I-——}.—+—^ 

AUXi { IWJRi iF: 

+-+-+-•+.-+-+_+_+_+ 

Where: R and W are the direction bits (read and write). 

F « I indicates that a "forced read" is desired <see GET 
CHARACTER and GET RECORD for more Information). 


CLOSE 

No special handler actions. 


GET CHARACTER and GET RECORD 

ERETURWT fr* 1 * f di ^° T “ i11 return data onl y when you press the 

fteyboard ' Houever, the «forced read" OPEN optioi 

RFAn n you , to read ts)ct daba witbout Intervention. When you command 
READ Operation, the Screen Editor will return data from the start o< 

_ line * n “bich the text Cursor is located, and then 

move the Cursor to the beginning of the following logical line A 

read of the last logical line on the screen will cause the screen 
Baxa so scroll, 

A special case occurs when characters are output without a 
termmating EOL, and then additional characters are appended to 
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that logical line from the keyboard. When the CRETURN2 key is 
pressed» only the keyboard entered characters are sent to the 
caller» unless the Cursor has been moved out of and then back 
into the logical line» in that case all of the logical line will 
be sent. 


PUT CHARACTER and PUT RECORD 

The Händler accepts ATASCII characters as one character per byte. 
Sixteen of the 256 ATASCII characters are control Codes; the EOL 
code has universal meaning. but mast of the other control codes 
have special meaning only to a display or print device. The 
Screen Editor processing of the ATASCII control codes is 
explainedbelow: 


CLEAR ($7D) — The Screen Editor clears the current display of 
all data and the Cursor is placed at the home position (upper 
left Corner of the screen). 

CURSOR UP ($iC> — The Cursor moves up by one physical line. The 
Cursor will wrap from the top 1ine of the display to the bottom 
1 ine. 

CURSOR DOWN ($1D> — The Cursor moves down by one physical line. 
The Cursor will wrap from the bottom line of the display to the 
top line. 

CURSOR LEFT (*1E) — The Cursor moves left by one column. The 
Cursor will wrap from the left margin of a line to the right 
margin of the same line. 

CURSOR RIGHT ($1F> — The Cursor moves right by one column. The 
Cursor will wrap from the right margin of a line to the left 
margin of the same line. 


BACKSPACE ($7E) — The Cursor moves left by one column (but never 
past the beginning of a logical line>» and the character at that 
new position is changed to a blank ($20). 
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SET TAB <$9F) — The Screen Editor establishes a tab point at the 
logical 1 ine position at that the Cursor is residing. The logical 
line tab position is not synonymous with the physical line column 
Position since the logical line can be up to 3 physical lines in 
length. For example« tabs can be set at the 15th, 30thi 45thi 
60th and 75th character positions of a logical line as shotun 
below: 


029 19 29 39 Screen column #. 

—{_-+-+-+-R L/R - margins. 

x x-T-T- A logical line. 

x x-T-T---T- x = inaccesible 

x x-- columns. 


Note the effect of the lef t marg in in defining the limits of the 
logical line. 


The Händler default tab settings are shoun below: 


0 2 

9 


19 

29 

39 

Screen column # 
L/R = margins. 

A logical line. 

L. 

x xT“ 

_ T _ 

_ T __. 

-T~ 

-T- 


x x — 

-T- 

- j — 

-T~ 

-T- 

-T 

x = inaccesible 

x x — 

- j - 

- 7 — 

-T- 

-T- 

-T 

columns. 


CLEAR TAB ($9E> — The Screen Editor clears the current Cursor 
Position within the logical line from being a tab point. There is 
no "clear all tab points“ facility provided by the Händler. 


TAB (*7F) — The Cursor moves to the next tab point in the 
current logical 1 ine t or to the beginning of the next line i f no 
tab point is found. This -Function ui 11 not increase the logical 
line length to accommodate a tab point outside the current length 
{e, g. the logical line length is 38 characters and there is a tab 
point at position 50). 


INSERT LINE (*9D) — All physical lines at and belou the physical 
line in that the Cursor resides» are moved down by one physical 
line. The last logical line on the display can be truncated as a 
result. The blank physical line at the insert point becomes the 
beginning of a neu logical line. A logical line can be split into 
tuo logical lines by this process. the last half of the original 
logical line being concatenated uith the blank physical line 
formed at the insert point. 
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DELETE LINE i$9CJ — The logical line in that the Cursor resides 
is deleted and all data below that line is moved upward to fill 
the void. Empty logical lines are created at the bottom of the 
displag. 


INSERT CHARACTER {$FF> — All physical characters at and behind 
the Cursor position on a logical line are moved one Position to 
the right. The character at the Cursor position is set to blank. 
The last character of the logical line will be lost when the 
logical line is full and a character is inserted. The number of 
physical lines comprising a logical line can increase as a result 
of this function. 


DELETE CHARACTER <$FE) — The character on uhich the Cursor 
resides is removed, and the remainder of the logical line to the 
right of the deleted character is moved to the left by one 
Position. The number of physical lines composing a logical line 
can decrease as a result of this function. 


ESCAPE <$IB) — The next non-EOL character following this code is 
displayed as data* even if it would normally be treated as a 
control code. The sequence CESC 3CESC3 will cause the second CESC 3 
character to be displayed. 


BELL ($FD> — An audible tone is generatedf the display is not 
modified. 


END OF LINE <$9B > — In addition to its record termination 
function* the EGL causes the Cursor to advance to the beginning 
of the next logical line. When the Cursor reaches the bottom line 
of the screen* the receipt of an EOL will cause the screen data 
to scroll upward by one logical line. 


GET STATUS 

The Händler takes no action other than to set the Status to $Oi. 


User-Alterab1e Data Base Variables 

Also see the Display Händler data base variable discussion. 
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Cursor Position 


When in a split-screen configuratiom ROWCRS and COLCRS are associated 
with the graphics portion of the display and two othsr variables f 
TXTROW C02901 and TXTCOL C0291]. are associated with the text uiindow. 
TXTROW is a single byte, and TXTCOL is 2-bytes tuith the least 
significant byte being at the louier address. Note that the most 
significant byte of TXTCOL should aluays be zero. 

The home Position <G, 0> for the text windotu is the upper left corner 
of the windotif. 


Enable/Inhibit of Control Codes in Text 

Normally all text mode control Codes are operated upon as received, 
but sometimes it is desirable to have the control Codes displayed as 
if they uere data characters. This is done by setting the variable 
DSPFLG C02FE3 to any nonzero value before outputting the data 
containing control codes. Setting DSPFLG to zero restores normal 
Processing of text control codes. 
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Cassette Händler (C: * 


The Cassette device is a read or turite device tuith a Händler 
that Supports the follotuing CIO -Functions: 


OPEN 

CLOSE 

GET CHARACTERS 
GET RECORD 
PUT CHARACTERS 
PUT RECORD 

GET STATUS (null Function) 


The Cassette Hand 1 er can produce the fol lotuing error statuses: 


*80 — CBREAK3 key abort. 

*84 — Invalid AUX1 byte on OPEN. 

*88 — end-oF-File. 

*8A-90 — SIQ error set (see Appendix C). 


The Cassette Händler is one oF the resident handlers/ and thereFore 
has a set oF device vectors starting at location E440. 


CIO Function Descriptions 

The device—speciFic characteristics oF the standard CIO Functions are 
detailed belotu: 


OPEN 

The device name is C, and the Händler ignores any device number and 
Filename speciFicationi ifincluded. 

The Händler supports the Follotuing Option: 
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AUX2 


7 0 

4 —+-+_ 4 —+-+-+-+-+ 

:c: i 


Where: C = i indicates that the cassette is to be read/written without 
stop/start between ?eca?ds (continuous mode). 

Opening the cassette for input generates a single audible tone» as a 
prompt for you to verify that the cassette player is set up 
for reading < p ower oni Serial Bus cable c onnec tedi tape cued to start 
of file; and PLAY button depressed). When the cassette is ready, 
you can press any keyboard key (except EBREAK3) to initiate tape 
reading. 

Opening the cassette for output generates two closely spaced audible 
tones, as a prompt for you to verify that the cassette player 
is set up for writing (as above, plus RECORD button depressed). When 
the cassette is ready, you can press any keyboard key (except 
EBREAK3) to begin tape writing. There is no way for the Computer to 
verify that the RECORD pr PLAY button is depressed. It is possible for 
the file not to be dritten, with no immediate indication of this fact. 

There is a potential problem with the cassette in that when the 
cassette is opened for (irriting, the motor keeps running unti 1 the 
first record (128 data bytes) is written. If 128 data bytes are 
written or the cassette is closed within about 30 seconds of the OPEN, 
and no other serial bus I/O is performed, then there is no problem. 
However, if those conditions are not met, some noise will be written 
to the tape prior to the first record and an error will occur when 
that tape file is read later. If lengthy delays are anticipated 
between the time the cassette file is opened and the time that the 
first cassette record <128 data bytes) is written, then a dummy record 
should be written as part of the filei typically 128 bytes of some 
innocuous data would be written, such as all zeros, all $FFs, or all 
blanks <* 20 >. 

The System sometimes emits whistling noises after cassette I/O has 
otcurred. The sound can be eliminated by storing $Ö3 to SKCTL ED20F3, 
thus bring POKEY out of the two-tone (FSK) mode. 


CLÜSE 


The 

CLOSE 

of a 

tape 

read stops 

the 

The 

CLOSE 

of a 

tape 

write does 

the 


cassette motor. 
following: 


Writes any remaining user data in the buffer to tape. 
Writes an end—of-file record. 

Stops the cassette motor. 
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GET CHARACTERS and GET RECORD 


The Händler returns data in the follotuing format: 


7 0 

I data byte ! 

+—l h—h—I— f 


PUT CHARACTERS and PUT RECORD 
The Hand 1er accep t s data in the f o 1 lotuing format: 

7 0 

! data byte i 

The Händler attaches no significance to the data bytes 
(uritteni a value of $9B (EQL) causes no special action. 

GET STATUS 

The Hand 1er does no more than set the status to $01. 


Theory of Operation 

The Cassette Händler ufrites and reads all data in fixed — length records 
of the format shown below: 


+._ 4 .„ + __ 4 ._ 4 ,_+_ + „ + _ + 

SO 1 0 1 0 1 0 1J 

4 — 4 ,_ + _ + _, + _ + _ + _ + _ + 

io l o i o i o li 

\ control byte I 

+ — y. — y. — + „ + _ + —I - y. 

i 128 : 

= data = 

\ bytes I 

+-+—).— y ——,—). 

! checksum \ 


Speed measurement bytes. 


CManaged by SIO, not the 
Händler. > 


Figure 5—9 Cassette Händler Record Format 
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The control by te contains one of t hree values: 

o ♦FC indicates the record is a full data record (128 bytes). 

o ♦FA indicates the record is a partially full data record; you 
supplied feiuer than 128 bytes to the record. This case can 
occur only in the record prior to the end-of-file. The number 
of user-supp1ied data bytes in the record is contained in the 
byte prior to the checksum. 

o ♦FE indicates the record is an End-of file record; the data 
Portion is all zeroes for an end-of-file record. 

The S10 routine generates and checks the checksum. It is part of the 
tape record» but it is not contained in the Hand 1er's record buffer 
CASBUF E03FD3. 

The Processing of the speed—measurement bytes during cassette reading 
is discussed in Appendix L, D1-D7. 


File Structure 

The Cassette Hand 1er wt i tes a file to the cassette device tirith a file 
structure that is totally imposed by the Händler (soft format). A file 
consists of the follouing three elements: 

o A 20-second leader of mark tone. 

o Any number of data-record frames. 

o An end-of-file frame. 


The cassette-data record frames are formatted as shoum below: 


frame = pre-record uirite tone (PRWT)» 
+ data record» 

+ post record gap (PRGJ 


The nondata portions of a frame have characteristics that are 
dependent upon the «rite OPEN mode» i.e. continuous or 
start/stop. 


Stop/start PRWT * 3 seconds of mark tone. 
Continuous PRWT = .25 second of mark tone. 


Stop/start PRG * up to i second of unknown tones. 

Continuous PRG =* from 0 to n seconds of unknoun tones» uihere 

n is dependent upon your program timing. 

The inter—record gap (IRG) bettifeen any tuo records consists of 
the PRG of the first record follofued by the PRWT of the second 
record. 
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Printer Händler (P: ) 


The Printer device is a turite—only device uii th a Hand 1er that 
supports the Follouiing CIO Functions: 

OPEN 

CLQSE 

PUT CHARACTERS 
PUT RECORD 
GET STATUS 

The Printer Händler can produce the Following error statuses: 

$8A-90 — SIO error set Csee Appendix C). 

The Printer Hand 1er is one oF the resident hand1 ers. and 
therefore has a set oF device vectors starting at location E430. 


CIO Function Descriptions 

The device-speciFic charaeteristics oF the Standard CIO Functions 
are detailed below: 


OPEN 

The device name is P. The Händler ignores any device number and 
Filename speeificatian. iF included. 


CLOSE 

The Händler uirites any data remaining in its buFFer to the 
printer device. tuith trailing blanks to Fill out the line. 


PUT CHARACTERS and PUT RECORD 
The Händler accepts print data in the Following Format: 


7 0 

•+•— y — y — y — y —|-|- y —*. 

S ATASCII ! 

+- y - y -).- y -j._ + - y - y 


The only ATASCII control code oF any signiFicance to the Händler 
is the EOL character. The printer device ignores bit 7 oF every 
data byte and prints a sub set oF the remaining 128 codes. (see 
Appendix G For the printer character set). 

The Händler supports the Follouing print Option: 
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AUX2 


7 0 

1 print mode S 

H-)- 1 -—I- t— -+ 


Wh ere: 


*4E <N> selects normal printing <40 characters per line). 
*53 <S) selects sideuays prlnting <29 characters per line). 
*57 (W) selects wide printing <not supported by printer 
device >. 

Any other value {including 00) is treated as a normal <N) 
print select* without producing an error status. 


GET STATUS 

The Händler obtains a 4-byte status Prom the printer 
Controller and puts it in System location DVSTAT I02EA3. The 
format oP the status bytes is shoun below: 


+ _. + „ + „ + _ + _ +-+ .. + _ + 


i command stat. ! 

DVSTAT + 

0 

i AUX2 oP prev. ! 

+ 

1 

+ 

i 

+ 

l 

+ 

l 

+ 

l 

+ 

l 

+ 

l 

+ 

i 

+ 

i 

+ 



{ timeout * 

+ 

2 

i (unused) ! 

+ 

3 


The command status contains the Pollowing status bits and 
condition indications: 

b it O: an invalid command frame uias received. 

bit 1: an invalid data frame was received. 

bit 7: an intelligent Controller (normally = 0). 

The next byte contains the AUX2 value Prom the previous Operation. 

The timeout byte contains a Controller provided maximum timeout 
value <in seconds). 


Theory aP Operation 

The ATARI 820CTM] 40—Co 1umn Printer is a 1ine—at—a—time printer rather 
than a character-at-a—time printer/ so your data must be buPPered by 
the Händler and sent to the device in records corresponding to one 
print line <40 characters for normal/ 29 characters Por sidetuays). 
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The printer device does not attach any significance to the EOL 
charac ter» so the Hand 1er does the appropriate blank fi11 
whenever it sees an EOL, 


Disk File Manager (D: ) 

The OS supports four unique File Management Subsystems at the 
time of this writing. Version IA is the original Version. 

Version IB is a slightly modified Version of IA and is the one 
described in this document. Most of this discussion applies as 
well to Version II, that handles a double-density diskette (720 
256-byte sectors) in addition to the sing1e-density diskette (720 
128-byte sectors). Version III has all new fi1e/directory/map 
structures and can possibly contain changes to your interface 
as well. 

The File Management Subsystem includes a d i sk-bootable 
(RAM-resident> Disk File Manager (DFM) that maintains a 
collection of named files on diskettes. Up to 4 disk drives 
(Dl: through D4:) can be accessed. and up to A4 files per 
diskette can be accessed. The System diskettes supplied by ATARI 
allow a single disk drive (Dl) and up to 3 OPEN files, but 
you can alter these numbers as described later in 
this section. 


The Disk File Manager supports the following CIO functions: 


OPEN FILE 
OPEN DIRECTORY 
CLOSE 

GET CHARACTERS 
GET RECORD 
PUT CHARACTERS 
PUT RECORD 
GET STATUS 


NOTE 

POINT 

LOCK 

UNLOCK 

DELETE 

RENAME 

FORMAT 
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The Disk File Manager can produce the Following error statuses: 


$03 — 
$88 — 
$8A-90 
$AG — 
$A1 — 
$A2 — 
$A3 — 
$A4 — 
$A5 — 
$A6 — 
$A7 — 
$A8 — 
$A9 — 
$AA — 
$AB — 


Last data From File (EOF on next read). 
end-oF-file. 

— SIG error set (see Appendix C). 

Drive numfaer specification error. 

No sector buFFer available (too mang open Files). 
Disk Full. 

Fatal I/O error in directory or bitmap. 

Internal File # mismatch (structural problem). 
File name speciFication error. 

Point inFormation in error. 

File locked to this Operation. 

Special command invalid. 

Directory Full (A4 Files). 

File not Found. 

Point invalid (File not OPENed For update). 


CIO Function Descriptions 

The device-speciFic characterist i cs oF the Standard CIO Functions 
are detailed belout: 


OPEN FILE 

The device name is D. Up to Four disk drives can be accessed (Dl 
through D4). The disk Filename can be From 1 to 8 characters in 
length with an optional 1“ to 3-character extension. 

The OPEN FILE command supports the Following options: 


AUXl 


7 0 

i ! W * R ! !A! 




Where: 


W and R are the direction bits. 

WR = 00 is invalid 

01 indicates OPEN For read only, 

10 indicates OPEN For write only. 

11 indicates OPEN For read/turite (update). 


A ~ 1 indicates appended output uhen W = 1. 
You mag use these Follouiing valid AUXl options: 
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OPEN Input <AUXi = $04) 

The indicated file is opened for input. Any wild—card eharacters 
are used to ssarch for the first match. If the file is not found* 
an error Status is returnedi and no file will fae opened. 


OPEN Output (AUX1 = $08) 

The indicated file is opened for output starting uiith the first 
byte of the file* if the file is not locfced. Any wild-card 
eharacters are used to search for the first match, If the file 
already exists* the existing file ufill be deleted before opening 
the named file as a neu) file. If the file does not already exist* 
it will be created. 

A file opened for output will not appear in the directory until 
it has been closed. If an output file is not properly closed* 
some or all of the sectors that were acquired for it can be lost 
until the disfc is reformatted. 

A file that is opened for output can not be opened concurrent1y 
foranyotheraccess. 


OPEN Append (AUXl = $09) 

The indicated file is opened for output starting with the byte 
after the last byte of the existing file (that must already 
exist)* if the file is not locked. Any wild-card eharacters are 
used to search for the first match. 

If a file opened for append is not properly closed* the appended 
data will be lost. The existing file will remain unmodified and 
some or all of the sectors that were acquired for the appended 
portion can be lost until the diskette is reformatted. 


OPEN Update (AUX1 = $0C) 

The indicated file <that must already exist) will be opened for 
update provided it is not locked. Any wild-card eharacters are 
used to search for the first match. 

The GET* PUT* NOTE and POINT operations are all valid* and can be 
intermixed as desired. 

If a file opened for update is not properly closed* a sector's 
worth of Information can be lost to the file. A file opened for 
update can not be extended. 
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Device/Filename Specification 

The Händler expects to find a device/filename specification of 
the following form: 


DLCnumberM : -Cf i lename><EQL> 
where: 

<Inumber> :: = i!2!3!4 

<filename> ::= C<primary>31. £Xextension>33<terminator> 

<primary> ::= an uppercase alpha character followed by D to 7 
alphanumeric characters. If the primary name is 
less than 8 charactersi it will be padded with 
blanks; if it is greater than 8 characters/ the 
extra characters will be ignored. 

<extension> ::« Zero to 3 alphanumeric characters. If the 
extension name is missing or less than 3 
characters/ it will be padded with blanks; if 
it is greater than 3 characters/ the extra 
characters will be ignored. 

<terminator> :: = <EOL>!<blank> 


Figure 5-10 Device/Filename Syntax 


The following are all valid device/fi1enames for the diskette: 

Dl: GAME. SRC 
D:MANUALS 
D:.WHY 
D3: FILE. 

D4:BRIDGE. 002 


Filename Wildcarding 

The filename specification can be further generalized to include 
the use of the “wild-card" characters * and ?. These wildcard 
characters allow portions of the primary and/or extension to be 
abbreviated as follows: 

The ? character in the specification allows any filename 
character at that position to produce a “match.“ For examplez WH? 
will match files named WHO/ WHY/ WH4/ etc./ but not a file named 
WHAT. 
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The * character causes the remainder of the primary or extension 
f i e ld in that it is used fco be effectively padded with ? 
characters. For example/ WH* will match WHO, WHEN, WHATEVER* etc. 

Some valid uses of wild-card specifications are shown below: 

*• SRC Files having an extension of SRC. 

BASIC.* Files named BASIC with any extension. 

*. * All files. 

H*. ? Files beginning with H and having a O or 1 

character extension. 

If wildcarding is used with an OPEN FILE command/ the first file 
found <if any) that meets the specificatian will be the one (and 
only one) opened. 


OPEN DIRECTORY 

The OPEN DIRECTORY command allows you read directory 
Information for the selected filename(s ), using normal GET 
CHARACTERS or GET RECORD commands. The Information read will be 
formatted as ATASCII records» suitable for printing ( as shown 
below. Wildcarding can be used to obtain information for multiple 
files or the entire diskette. 

The OPEN DIRECTORY command uses the same CIO Parameters as a Standard 
OPEN FILE command: 

COMMAND BYTE *= $03 

BUFFER ADDRESS = pointer to device/fi1ename specif ication. 

AUX1 *> *06 

After the directory is opened; a record will be returned to the 
caller for each file that matches the OPEN specification, The 
record; that contains only ATASCII characters/ is formatted as 
shown below: 


1 

123456789012345678 
fsib! primary name ! ext iblcountie! 

4-1-1-1-1-)-)-h—t-—h—I-1-1-1-)-1-1-i-1- 
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Where: s = * or ' uith * indicating file locked. 
fa = blank. 

primary name » left-justified name uiith blank fill. 
ext *= left-justified extension with blank fill. 
b - blank. 

count = number of sectors comprising tba file. 

8 = EOL < *9B). 

After the last filename match record is returned/ an additional 
record is returned. Tbis record indicates the number of unused 
sectors available on the disketts. The format for this record is 
belau: 


1 

12345678901234567 

"V +—•+--+—+—— y- —4- -— 4 —&— “4—+ 

icaunt! FREE SECTQR S!ei 

+~+-+-+-+-+-+- + *-+“+- 4 —+“ + -+- + -+-+-+ 

Where: count = the number of unused sectors on the diskette 
e = EOL <*9B>. 

The EOF statuses <*03 and *88) are returned as in a normal data 
file fifhen the last directory record is read. 

The opening of another diskette file uhile the directory read is 
open will cause subsequent directory reads to malfunctiom so 
care must be taken to avoid this Situation. 


CLOSE 

Upon closing a file read* the Hand 1er releases all internal 
resources being used to support that file. 

Upon closing a file write* the Händler: 

o writes any residual data from its file buffer for that file 
to the diskette. 

o Updates the directory and allocation map for the associated 
diskette. 


o releases all internal resources being utilized to Support 
that file 


GET CHARACTERS and GET RECGRD 

Characters are read from the diskette and passed to CIO as a raur 
data stream. None of the ATASCII control characters have any 
special significance. A status of *88 is returned if an attempt 
is made to read past the last byte of a file. 




shoun 
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PUT CHARACTERS and PUT RECORD 


Characters are obtained from CIO and written to the diskette as a rau) 
data stream. None of the ATASCII control characters have any special 
significance. 


GET STATUS 

The indicated file is checked and one of the follotuing Status 
byte values is returned in ICSTA and register V: 

$01 — File found and unlocked. 

$A7 — File locked. 

$AA — File not found. 


Special CIO Functions 

The DFM Supports a number of SPECIAL commands> that are device 
specific. These are explained in the paragraphs that foll dli: 


NÖTE (COMMAND BYTE * $25) 

This command returns to the caller the exact diskette location of 
the next byte to be read or writteni in the variables shotun 
belou: 

ICAX3 as LSB of the diskette sector number. 

ICAX4 = MSB of the diskette sector number. 

ICAX5 = relative sector displacement to byte (0-124). 


POINT (CQMMAND BYTE » $2&) 

This command allows you to specify the exact diskette location of 
the next byte to be read or uritten. In Order to use this commmandi 
the file must have been opened with the "update" option. 

ICAX3 = LSB of the diskette sector number. 

ICAX4 = MSB of the diskette sector number. 

ICAX5 = relative sector displacement to byte (0-124). 
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LOCK 


Th i s c ommand all ows y ou to prevent wr i te access to any 
number of named files. Locked files can not be deleted* renamed* 
nor opened for output unless they are first unlocked. Locking a 
file that is already locked is a valid Operation. The Händler 
expects a device/filename specification; then all occurrences of 
the filename specified will be locked* using the uild-card rules 

You set up these follouing IOCB parameters prior to 
calling CIO: 

COMMAND BYTE = »23 

BUFFER ADDRESS *= pointer to device/f i lenatne spec if icat ion. 

After a LOCK Operation* the follouing IOCB parameter will have 
been altered: 

STATUS = result of LOCK Operation; see Appendix B for a list 
of possible Status codes. 


UNLOCK 

Th is command a 1 laus you to remove the lock status of any 
number of named files. Unlocking a file that is not locked is a 
valid Operation. The Händler expects a device/filename 
specification; then all occurrences of the filename specified 
will be unlocked* using the wild-card rules. 

You set up these follouing IOCB parameters prior to 
calling CIO: 

COMMAND BYTE = »24 

BUFFER ADDRESS = pointer to device/fi1ename specification. 

After an UNLOCK Operation* the follouing IOCB parameter will have been 
a1tered: 

STATUS = result of UNLOCK Operation* see Appendix B for a 
list of possible status codes. 


DELETE 

This command allous you to delete any number of unlocked 
named files from the directory of the selected diskette and to 
deallocate the diskette space used by the files involved. The 
Hand 1er expects a device/filename specification* then all 
occurences of the filename specified will be deleted* using the 
wild-card rules. 
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You set up tfiese following IQCB Parameters prior to 
calling CIO: 


COMMAND BYTE « *21 

BUFFER ADDRESS = pointer to device/filename specification. 

After a DELETE Operation! the following IOCB parameter will have 
been altered: 

STATUS = result of DELETE Operation; see Appendix B for a list of 
possible status codes. 


RENAME 

Tftis command allows you to cbange the filenames of any 
number of unlocked files on a single diskette. The Händler 
expects to find a device/filename specification that follows: 

<device spec>: -Cf i lename sp ec>i <If i lename specXEOL> 

All occurrences of the first filename will be replaced with the 
second filename, using the wild-card rules. No protection is 
provided against forming duplicate names. Qnce formed» duplicate 
names cannot be separately renamed or deleted; however, an QPEN 
FILE command will always select the first file found that matches 
the filename specification, so that file will always be 
accessible. The RENAME command does not alter the content of the 
files involved, mere1y the name in the directory. 

Examples of some valid RENAME name specifications are shown 
below: 

Dl: *. SRC, #. TXT 
D:TEMP,FDATA 
D2: F*, F*. OLD 

You set up these follotuing IOCB Parameters prior to 
calling CIO: 

COMMAND BYTE = *20 

BUFFER ADDRESS = pointer to device/fi1ename specification. 

After a RENAME Operation, the following IOCB parameter will have 
been altered: 

STATUS result of RENAME Operation; see Appendix B for a 
list of possible status codes. 
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FORMAT 


Soft-sector diskettes must be formatted before they can störe 
data. The FORMAT tommand allows you to physically Format a 
diskette. The physical formatting process writes a new copy of 
every sector on the soft-sectored diskette, with the data portion 
of each sector containing all zeros. The FORMAT process creates 
an "empty" non System diskette. When the formatting process is 
complete, the FMS creates an initial Volume Table of Contents 
(VTOC) and an initial File Directory. The boot sector (#1) is 
permanently reserved as part of this process. 

You set up these following IOCB parameters prior to 
calling CIO: 

CÖMMAND BYTE = *FE 

BUFFER ADDRESS ** pointer to device spec if icat ion. 

After a FORMAT Operation, the following IOCB Parameter will have 
been altered: 

STATUS = result of FORMAT Operation; see Appendix B for a 
list of possible status codes. 

To create a System diskette, a copy of the boot file must then be 
written to sectors #2~n. This is accomplished by writing the file 
named DOS.SYS. This is a name that is recognized by the FMS even 
though it is not in the directory initially. 


Theory of Operation 

The resident OS initzates the disk-boot process (see Section 10). 
The OS reads diskette sector #1 to memory and then transfers 
control to the "boot continuation address" (boot address + 6). 

The boot-continuation program contained in sector #1 then 
continues to load the remainder of the File Management Subsystem 
to memory using additional Information contained in sector #1. 

The File Management Subsystem loaded, will contain a Disk File 
Manager ,and optionally, a Disk Utilities (DOS) package. 

When the boot process is complete, the Disk File Manager will 
allocate additional RAM for the creation of sector buffers. 

Sector buffers are allocated based upon Information in the boot 
record as shown below: 

Byte 9 = mal imum n umber of open files; orte buff er per (the 
maximum value is 3). 

Byte 10 = drive select bits; one buffer per (1-4 only). 
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The Disk File Manager will then insert the name D and the Händler 
vector table address in thedevice tab le. 

NOTE: There is a discrepancy betuieen the Disk File Manager's 
numbering of diskette sectors <ö—7191 and the d is k Controller's 
numbering of diskette sectors (1—720); as a result/ an ly sectors 
1- 719 are used by the Disk File Manager. 

The Disk File Manager uses the Disk Händler to perform all 
diskette reads and writes; the DFM's function is to support and 
maintain the directory/file/bitmap structures as described in the 
f ol lotuing pages: 
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FMS Diskette Utiiization 


The map belotu shoufs the Diskette sector utiiization for a 
Standard 720 sector diskette. 


+ - + 

' BOOT record { Sector 1 

+ - + 

i FMS BOOT i Sector 2 -+ 

= file = ! 

! DOS. SYS i Sector n +- Note i 


i User ' Sector n+1 -+ 

= File 

i Area i Sector 359 <4167) 

+ — — *” ——“ “ — “ — “■“ + 

{ VTÜC<note 2) I Sector 360 <4168) 

+ - + 

i File ! Sector 361 ($169) 

= Directory = 

i i Sector 368 <4170) 

* User f 

= File = 

l Area 1 Sector 719 <42CF> 

+ - + 

\ unused ! Sector 720 (42DG) 

+ -+ 


Figure 5—11 File Management Subsystem Diskette Sector Utiiization 
Map 


NOTE 1 - If the diskette is not a System diskette* then your 
File Area starts at sector 2 and no space is reserved for the FMS 
BOOT file. Hoüfever, "DOS" (DOS. SYS and DUP. SYS) may still be 
(dritten to a diskette that has already used sectors "2-N. 11 

NOTE 2 — VTOC Stands for Volume Table of Contents. 
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FMS Boot Record Format 


The FMS BOOT record (sector #1) is a special case of diskette-booted 
Software (see Section 10). The format for the FMS BOOT record is 
shoum below: 


JMP * $4B 

boot read 
+ continuation 
address 


boot flag = 0 
# sectors ~ 1 
boot address 
- 0700 
init address 


max files = 3 


drive bits 

■ 1 

alloc dirc 

- 0 

boot image 

end 

address + 

1 

boot flag 

o 

A 

V 

sector count 


DOS. SYS 
starting 
sector number 


code for second 
phase of boot 


Byte 0 
1 
2 


9 

10 

11 


14 

15 


Note 1 
Note 2 
Note 3 


FMS 

- configuration 

data 

Note 4 
Note 5 


Figure 5—12 File Management Subsystem Boot Record Format 
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NOTE 1 

NOTE 2 

NOTE 3 

NOTE 4 

NOTE 5 


- Byte 9 specifies the maximum number of concurrently open 
files to be supported. This value can ränge from 1 to 8. 


- Byte iO specifies 
supported using a 


tbe specific disk drive numbers to be 
bit encoding scheine as sfiotun beloui: 


76543210 

J !4i3!2!l! tuhere a 1 indicates a selected drive. 

+“+- + ,w, + ta ' + ,, * + "' , f'“ + ‘*" + 


Byte 11 specifies the buffer allocation direction, this 
byte should equal 0. 


- Byte 14 must be nonzero for the second phase of the boot 
process to initiate. This flag indicates that the file 
DOS. SYS has been written to the diskette. 


- This byte is 
DOS. SYS file. 


assigned as being the sector count 
It is actually an unused byte. 


for 


the 
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Boot Process Memory Map 


The diagram beloui shows how the boot sector (part of file 
DOS. SYS) and following sectors are loaded to memory as part of 
the boot process. 


■+ Memory address 0700 


! data from boot ! I 

- sector read by “ J 

i resident OS 1 077C 

+ - + 

[ data from rest 3 0770 

: of dos. sys i i 

I read by the 3 I 

= program in the * l 

* boot sector. ! t 

i ! L 

+-+ end of boot 


Figure 5-i3 File Management Subsystem Boot Rrocess Memory Map 
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Volume Table of Contents 


The format for the FMS volume table of contents (VTOC, sector 
360) is shouin in the d iagram he lou: 


directory 

type 

maximum 

(io) 

sector # 


= 02C5 

(hi ) 

number of 

(lo) 

sectors 


available 

(hi ) 



= volume bit map = 


+-■—► 


+■ 


■+ 


Byte 0 Note 1 
1 Note 2 

3 Note 3 


10 


Figure 5-14 File Management Subsystem Volume Table of Contents 
The volume bit map Organization location follows: 


7 0 
! U 2 3 4 5 6 7! 
!8 9.! 


■i -1-1-1- i- —|-)-—I-h 

Figure 5-15 File Management Subsystem Volume Bit Map 

At each map bit position/ a 0 indicates the corresponding sector 
is in use and a 1 indicates that the sector is available. 


Byte 10 of VTOC 
11 


NOTE 1 


The directory type byte must eq,ual O. 


NOTE 2 


The maximum sector 
incorrectly set to 
number is actually 


number is not used because it is 
709 decimal. The true maximum sector 
719 for the DFM. 
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NOTE 3 - The number of sectors available is initially set to 709 
after a Diskette is freshly formatted; this number is 
adjusted as f i les are created and de 1 eted to shoiu the 
number of sectors available. The sectors that are 
initially reserved are 1 and 360-368. 


File Directory Format 

The FMS reserves eight sectors <361-368) for a file directory. 
Each sector containing directory information for up to eight 
filesi thus providing for a maximum of 64 files for any volume. 
The format of a single 16-byte file entry is shoun belotu: 


T" 

« 

t 

flag byte 

- + 

1 

t 





( 

i 

sector 

< lo) 

i 

t 

+ 

count 


+ 

i 

i 


(hi) 

t 

1 





l 

i 

starting 

< lo) 

t 

t 

+ 

sector 


+ 

i 

i 

numb er 

(hi) 

1 

4 





t 

t 


(1 > 

1 

1 

+ 



+ 

i 

t 


(2) 

1 

1 

+ 



+ 

< 

f 


(3) 

1 

1 

+ 



+ 

i 

i 

file 

(4) 

t 

f 

+ 



+ 

i 

t 

name 

(5) 

1 

1 

+ 



+ 

l 

i 

primary 

(6) 

t 

t 

+ 



+ 

i 

t 


(7) 

1 

1 

+ 



+ 

t 

i 


(8) 

t 





t 

f 

file 

(1 > 

1 

t 

+ 



+ 

i 

i 

name 

(2) 

t 

t 

+ 



+ 

t 

f 

extension (3) 

I 

i 

+■ 


-- - 

-+ 


Byte 0 
i 

3 

5 


13 


Figure 5—16 File Directory Format 


Where the flag byte has the follotuing bits assigned: 


— Section 5 
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bit 7 * 1 if the file bas been deleted. 

bit 6 = l if the file is in use. 

bit 5 = 1 if the file is locked. 

bit 0 = 1 if OPEN output. 


The flag byte can take on the following values: 


*QO = entry 
*40 * entry 
*41 » entry 
*60 - entry 
*80 = entry 


not yet used (no file). 
in use (normal CLGSEd file). 
in use (OPEN output file). 
in use (locked file). 
available (prior file deleted). 


Sector count is the number of sectors eomprising the file. 


FMS File Sector Format 

The f ormat of a sector in your data file is shown bei out: 


7 0 

fX. HB 


1 data ! 

t 1 

f i 

+0 

: file # ! h i : 

+ 125 

T T “ “ T 

Iforward pointer! 

|L-|1| IIII ±L..I>W 4t I j •• Lr -I- 

+ 126 

.M-T T r““ 

SS! byte count < 

+—j .—y —j.—f.—|-|-+ 

+ 127 


Figure 5-17 File Management Subsystem File Sector Format 


The FMS uses the file # to verify file integrity. The file # 
is a redundant piece of Information. The file number field 
contains the value of the directory position of that file. If a 
mismatch occurs between the file's directory position/ and the 
file number as contained in each sector» then the DFM will 
generate the error *A4. 

The forward pointer field contains the 10—bit value for the 
diskette sector number of the next sector of the file. The 
pointer equals zero for the last sector of a file. 

The S bit indicates whether or not the sector is a “short sector“ 
(a sector containing fewer than 125 data bytes). S is eq_ual to 
1 when the sector is short. 
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The byte-count field contains the number of data bytes in the 
sec tor. 


Non-CIO I/O 

Seme portions of the I/O subsystem are accessed independent ly of 
the Central I/O Utility (CIÖ>; this section diseusses those 
areas. 


Resident Device Händler Vectors 

All of the OS ROM resident device handlers can be accessed via 
sets of vectors that are part of the OS ROM. These vectors 
increase the speed of I/O operations that utilize fixed device 
assignments/ such as output to the Display Händler. For each 
resident Händler there is a set of vectors ordered as shoun 
below: 


1 1 
+ + ■ 

OPEN 

—+ 

-+ 

+o 


CLOSE 


+3 

+- 

GET BYTE 


+4 


PUT BYTE 

-+ 

+6 


GET STATUS 

-+ 

+8 

+*" 

SPECIAL 


+ 10 

+** 

+- 

JMP 

INIT 

- 4 * 

—f 

+ 12 

+ — 

+- 

+ — 

SPARE 

BYTE 

—+ 

-+ 

-+ 



Figure 5-18 Resident Device Händler Vectors 


See Section 9 for a detailed description of the data interface 
for each of these Händler entry points. 

Each of the vectors contains the address <lo,hi) of the Händler 
entry point minus 1. A technique similar to the one shown belotif 
is required to access the desired routines: 
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VTBASE=*E400 


i BASE OF VECTOR TABLE. 

LDX 

#x X 

; OFFSET TO DESIRED ROUTINE. 

LDA 

data 


JSR 

GOVEC 

; SEND DATA TO ROUTINE. 

LDX 

#yy 

; OFFSET TO DIFFERENT ROUTINE 

JSR 

GOVEC 

i GET DATA FRQM ROUTINE. 

STA 

data 



GOVEC TAY 


i SAVE REGISTER A. 

LDA 

VTBASE+1,X 

i ADDRESS MSB TO STACK 

PHA 



LDA 

VTBASE,X 

; ADDRESS LSB TO STACK 

PHA 



TYA 


; RESTORE REGISTER A. 

RTS 


; JUMP TO ROUTINE. 


The JMP INIT slot in each set of vectors Jumps to the Händler 
initialization entry (not minus 1). 

The base address of the vector set for each of the resident 
handlers is shoum belou: 


Screen Editor (E:) E4Ö0. 
Display Händler <S:) E410. 
Keyboard Händler (K:) E420. 
Printer Händler <P:i E430. 
Cassette Händler (C:) E440. 


The resident diskette Händler is not CIö-compatib1e. so its 
interface does not use a vector set. 


Resident Diskette Händler 

The resident Diskette Händler (not to be confused tifith the Disk 
File Manager) is responsible for all physical accesses to the 
diskette. The unit of data transfer for this Händler is a single 
diskette sector containing 128 data bytes. 

Communication between you and the Diskette Händler is 
effected using the system's Device Control Block (DCB), that is 
also used for Handler/SIO communication (see Section 9). The DCB 
is 12 bytes long. Some bytes are user-alterable and some are for 
use by the Diskette Händler and/or the Serial I/O Utility <SIÖ). 
You supply the reyuired DCB parameters and then do a JSR 
DSKINV CE4531. 
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Each of the DCB bytes will now be described- and the 
system-equate file name for each will be given. 


SERIAL BUS ID — DDEVIC C03003 

The Diskette Händler sets up this byte to contain the Serial Bus ID 
for the drive to be accessed. It is not user-aIterable. 


DEVICE NUMBER — DUNIT C03013 

You set up this byte to contain the disk drive number to be 
accessed (1-4). 


CÖMMAND BYTE — DCOMND CÖ3023 

You set up this byte to contain the disk device command to 
be performed. 

STATUS BYTE — DSTATS C03033 

This byte contains the status of the command upon return to the 
cal1 er, See Appendix C for a list of the possible status codes. 


BUFFER ADDRESS — DBUFLO C03043 and DBUFHI C03053 

This 2-byte pointer contains the address of the source or 
destination of the diskette sector data. You need not supply 
an address for the disk status command. The Disk Händler will 
obtain the status and insert the address of the status buffer 
into this field. 


DISK TIMEOUT VALUE — DTIMLO C030&3 

The Hand 1er supplies this timeout value (in whole seconds) for 
use by SIQ. 

BYTE COUNT — DBYTLO C03083 and DBYTHI C03Ö93 

This 2-byte counter indicates the number of bytes transferred to 
or from the disk as a result of the most recent command- and is 
set up by the Händler. 

SECTOR NUMBER — DAUX1 C030A3 and DAUX2 I03GB3 

This 2-byte number specifies the diskette sector number (1 - 720) 
to read or write, DAUX1 contains the least significant byte- and 
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DAUX2 c ontains the most signiPicant byte. 


Diskette Händler Commands 

There are Pive commands supported by tbe Diskette Händler: 

GET SECTOR (PUT SECTOR —### not supported by current bandler #**) 
PUT SECTOR WITH VERIFY 
STATUS REQUEST 
FORMAT DISK 


GET SECTOR (Command byte = $52) 

Tbe Händler reads the speciPied sector to your buPPer and returns the 
operation status. You set the Pollowing DCB parameters prior to 
calling the Diskette Händler: 

COMMAND BYTE = $52. 

DEVICE NUMBER = disfc drive number (1-4). 

BUFFER ADDRESS = pointer to your 12S-byte buPPer. 

SECTOR NUMBER = sector number to read. 

Upon return Prom the sector* several oP the other DCB Parameters 
will bave been altered. The STATUS BYTE will be the only 
Parameter oP interest to you» however. 


PUT SECTOR (Command byte — $50) 

**•# Not supported by current Händler 

(But can be accessed through SIO directly.) 

The Händler writes tbe speciPied sector Prom your buPfer and returns 
the Operation Status. You set the Pollowing DCB Parameters prior to 
calling the Diskette Händler: 

COMMAND BYTE = $50. 

DEVICE NUMBER = disk drive number (1-4). 

BUFFER ADDRESS — pointer to your 128 byte buPPer. 

SECTOR NUMBER = sector number to write. 

Upon return Prom the Operation» several oP tbe other DCB Parameters 
will bave been altered. The STATUS BYTE will be the only one oP 
interest you» however. 
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PUT SECTÜR WITH VERIFY (Command Byte = *57) 


The Händler writes the specified sector from your buffer 
and returns the Operation status. This command differs from PUT 
SECTOR in that the diskette Controller reads the sector data after 
writing to verify the write Operation. Aside from the COMMAND 
BYTE value, the calling sequence is identical to PUT SECTOR. 


STATUS REQUEST (Command byte = *53) 

The Händler obtains a 4-byte Status from the disfcette Controller and 
puts it in system location DVSTAT C02EA3. The Operation status 
format is shown below: 


7 0 


! command stat. ! 

DVSTAT + 

0 

\ hardware stat .\ 

+ 

1 

+ _ + _+_ + _ + _ + _ + _ + _ + 



i timeout i 

+ 

2 

! (unused) 1 

+ 

3 


Figure 5-19. DVSTAT 40-Byte Operation Status Format 

The command status contains the following status bits: 

Bit 0=1 indicates an invalid command frame was received. 

Bit 1=1 indicates an invalid data frame was received. 

Bit 2=1 indicates that a PUT Operation uas unsuccessful. 

Bit 3=1 indicates that the disfcette is urite protected. 

Bit 4=1 indicates active/standby. 

The harduare status byte contains the status register of the 
INS1771-1 Floppy Disfcette Controller chip used in the disfcette 
Controller. See the documentation for that Chip to obtain 
Information relating to the meaning of each bit in the byte. 

The timeout byte contains a contro1ler-provided maximum timeout 
value (in seconds) to be used by the Händler. 

You set the follouing DCB parameters prior to calling 
the Diskette Händler: 

COMMAND BYTE = *53. 

DEVICE NUMBER * disk drive number (l-4>. 

Upon return from the operation> several of the other DCB parameters 
will have been altered. The STATUS BYTE will be the only one of 
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Interest to you. however. 


FORMAT DISK <Command Byte = *21) 

The Händler eommands the diskette Controller to format the entire 
diskette and then to verify 1t. All bad sector numbers <up to a 
maximum of 63) are returned and put in the supplied buffer. 
fo1lowed by two bytes of all 1 's <*FFFF). You set up the 
following DCB parameters prior to calling the Diskette Händler: 

COMMAND BYTE = *21. 

DEVICE NUMBER =» disk drive number (1-4). 

BUFFER ADDRESS = pointer to your 128-byte buffer. 

Upon return, you might be interested in the following DCB parameter 
STATUS BYTE = Status of Operation. 

BYTE COUNT - number of bytes of bad sector information in 
your buffer. not including the *FFFF terminator. If there 
are no bad sectors. the count will equal zero. 


Serial Bus I/O 


Input/Output to devices other than the keyboard. the screen. and 
the ATARI Computer Controller port devices. must utilize the 
Serial I/O bus. This bus contains data, control. and clock lines 
to be used to allow the Computer to communicate with external 
devices on this "daisychained" bus. Every device on the bus has 
a unique identifier and will respond only when directly 
addressed. 

The resident System provides a Serial I/O Utility (SIQ). that 
provides a standardized high-level program interface to the bus. 
SIO is utilized by the resident Diskette. Printer, and Cassette 
handlers. and is intended to be used by nonresident handlers (see 
Section 9). or by app1ications. as well. For a detailed 
description of the program/SIO interface and for a detailed bus 
specification refer to Section 9. 
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